System Booster/System Booster.iso/Archives/ForCLI/CRLF13.lzh/crlf.doc

Text File | 1991-10-15 | 13.2 KB | 382 lines

                        CRLF 1.3   by V. Gervasi


        CRLF is a handy program to convert format of ASCII files between
        different machines, and can be used to produce double- or
        triple-spaced texts, too.



 1.     The Problem

     Even if ASCII is one of the few standards that are standard enough to
     simplify the life of us poor users, different machines and different
     OSs often use different convention to signify end-of-line.
     As an example, the AmigaOS uses the "LF" code (decimal 10), the
     Macintosh uses "CR" (decimal 13), MS-DOS uses "LF/CR" (waste of
     space, even if more correct) and so on.

     Since I found myself often porting software and docs between these
     machines (among other...), I decided to write a little utility to
     solve the problem. I hope it will help you in some way !



 2.     The Solution

     CRLF will read any amount of input, in any end-of-line style (it will
     decide by himself) and output the same text, in a convention of your
     choice. Various options are available to determine the end-of-line
     convention to use, the source and the destination of the work and
     some other aspect. I beleive the I/O options are quite extensive.



 3.     What CRLF WON'T do

     CRLF is a very simple-minded program. You cannot feed it arbitrary
     data (such as WP documents, graphics, executables...) to convert
     to other systems... "we are still working on it".
     CRLF will not attempt any formatting of the resulting data. So, no
     80-column word-wrap around or other frills (I suggest you to use some
     other filter-style program to do such things), nor will it transla-
     te strange character (code >127), nor even normal ones, for this
     matter.
     All what CRLF do is to change the end-of-line style. Stop.



 4.     Options

     CRLF may be given very complex command lines. Here is a summary:

     The basic format of the command is

                CRLF [options] [files]

     where [...] means that element is optional. However, options and
     files may be mixed together without harm; CRLF will first scan the
     arguments collecting options, then will work on the given files.

     At present release (1.3), these options are available:

        -cr     output will have a cr at end of line (*)
        -lf     output will have a lf at end of line (*)
        -A      output will be in Amiga format (lf)
        -M      output will be in Macintosh format (cr)
        -D      output will be in MS-DOS format (cr/lf)
        -U      output will be in UNIX format (lf)

     (*) You can specify up to 16 of these options; cr's and lf's will
         be outputted following the order of the parameters.

        -v      be verbose (prints the file names as it processes them)

        -b<n>   set I/O buffers size to <n>; default is 16384.
                If <n> is lower than 512, a value of 512 will be used.

        -s<s>   append <s> after the name of the input file to obtain
                the name of the output file
        -p<s>   prepend <s> before the name of the input file to obtain
                the name of the output file
        -!      overwrite the input file, convert "in place"


     If no file is given, stdin & stdout will be used, so that CRLF
     acts as a true "UNIX style" text filter.

     If no -s, -p or -! option is given, CRLF will regard the given file
     names as <input,output> pairs, until the list is exhausted.

     If no -cr, -lf, -A, -M, -D or -U is given, the default is -A.

     If -s, -p or -! IS given, you can use AmigaDOS patterns as file names.

     If you give a -s or -p without any <string>, the default is to use
     the empty string "", but CRLF will act as in "suffix" or "prefix"
     mode (thus allowing patterns).

     "CRLF ?" will print an help page.

     Note: Some options are mutually exclusive:
           * -A,-M,-D,-U are incompatible each other and with any -cr or -lf;
           * -cr and -lf may be given together, but not in conjunction with
             any other "style" option (-A,-M,-D or -U);
           * -p and -s may be given together, but not with -! ;
           * -! may not be given with a -p or -s;
           * -v may be given with any other combination of options.

     Apart from -cr, -lf and -v, options may not be given more than one
     time. Specifying multiple -v is a no-op, while specifying more -cr
     and -lf describes the custom eol-style to use.

     Any other word not starting with a "-" is taken to be a file name.



 5.     CRLF behaviour

     After collecting options, CRLF start analyzing the given files.

     If no file is given, CRLF assumes stdin as input and stdout as output
     and starts converting until End-Of-File is reached (from the keyboard,
     this may be simulated with a CTRL-\).
     Every -s, -p or -! is ignored, since there are no files involved.

     If -s or -p was specified (even with null strings as arguments),
     CRLF goes to "suffix/prefix" mode. It will use the given file names
     as input, and the <prefix><base name><suffix> strings as output file
     names (<base name> is the name of the file, minus the path).
     If verbose is active, these names will be printed to the standard
     output.

     If -! was specified, CRLF goes to "overwrite" mode. It will use the
     given file names as input, will put output in a temporary file that
     will be created in the "T:" directory, if no volume or directory was
     present in the original file name, otherwise in the same directory as
     the original.
     After the conversion, CRLF will REMOVE the original file and RENAME
     the temporary file to the old name.
     The RENAME operation will be performed via a DOS rename if possible,
     via a copy/delete of the temporary file otherwise.
     Note that there is always at least one copy of the file, so damage in
     case of failure should be minimal.

     If no -s, -p or -! was specified, CRLF goes to "twin" mode.
     Each couple of file given is taken to signify <input,output>.
     CRLF will convert the FIRST file of the couple, leaving the result in
     a file named as the SECOND file.
     If you specify "::" as the name of the second file, it is taken to
     mean "stdout" (since :: is not a valid file name).
     Obviously, there must be an even number of file names...
     In case of an ODD number of names, the last one is ignored silently.



 6.     CRLF Limits

     CRLF holds some internal buffer to do his work. Here are the limits:

        * max 16 -cr/-lf specifiers;
        * max cumulative length of all file names resulting from a single
          pattern expansion is 16384 chars;
        * max lenght of a "base" name (file name without path) is limited
          to 50. Note that current AmigaDOS has a limit of 30.
        * min lenght of I/O buffers is 512; there is no max value.
          CRLF will try to allocate 2 of this buffers; the bigger the
          buffers, the faster the processing. However, the default of
          16384 should work fine in every situation.



 7.     CRLF Messages

        "Warning: Cannot mix xxx and yyy, xxx ignored"

                You have specified two incompatible options; the former
                will be retained and the latterd discarded.
                See above, section 4, for details.

        "Warning: Too many -cr/-lf options, xxx ignored"

                You have exceeded the limit of 16 -cr/-lf specifiers.
                Any -cr/-lf in excess will be ignored.

        "ERROR: Unknown option xx, ignored"

                You put an illegal option in the command line.
                If you have a file starting with a "-" you are in troubles.
                Try substituting the dash with a "?".
                See sections 4 and 5 for details.

        "PANIC: Out of memory - cannot build outfile name"

                Your system is very low on memory. Execution is aborted.
                Try freeing some memory (closing windows, quitting other
                applications).

        " xxx -> yyy"

                You have set verbose mode.
                CRLF is converting xxx's end-of-line style, result will
                be found in yyy.

        "ERROR: Cannot open output file xxx"

                For some reason, file xxx cannot be opened for writing.
                Current conversion will be skipped.

        "WARNING: Cannot open input file xxx"

                For some reason (usually a non-existing file or a file in
                exclusive use of some other program), file xxx cannot be
                opened for reading.
                Current conversion will be skipped.

        "WARNING: Buffers size too low, set to xxx"

                You set an I/O buffers size too small. Minimum is 512.
                Just ignore the message, or remove the -b option, or simply
                set an higher value.

        "ERROR: Cannot allocate buffer to copy xxx"

                CRLF could not allocate a buffer to copy xxx to his natural
                place (in overwrite mode). You are left with the converted
                file in xxx instead of having it overwrite the original.

        "WARNING: Cannot rename xxx"
        "WARNING: Cannot copy it to yyy"

                In overwrite mode, CRLF could not rename, nor copy the
                temporary file xxx to yyy. Maybe some file is protected,
                or a device is read/only, or T: has disappeared (!).

        "ERROR: Cannot re-open xxx"

                This is a strange error, since the program just finished
                writing a file xxx and cannot re-open it. Maybe the
                temporary file was created on a write-only device ?



 8.     CRLF Bugs

     None known at the moment.



 9.     CRLF History


     1.0        11-Mar-91

                First release. Seems to work.

     1.1         5-Apr-91

                Emended some minor bugs and refined documentation.

     1.2        30-May-91

                Removed limit on max line lenght (to accomodate for
                HP-48 GROBs...)



10.     Examples

     "crlf"

        Simplest form, convert from any input in stdin to Amiga format
        in stdout. May be used with redirection or with pipes, if your
        shell supports pipes.

     "cat #? | crlf >ser:"

        This will collect together all the files in the current directory
        and send them (converted to Amiga format) to the serial port.

     "crlf <ser: >prt:"

        This will receive his input from the serial port (pheraphs
        connected to some other machine) and print it to the system
        printer, in Amiga format.

     "crlf <ser: >prt: -lf -lf"

        As above, but double-spaced.

     "crlf ms0:CRYPT.ASM Work:crypt.s"

        We work in twin-mode. File ms0:CRYPT.ASM (in MS-DOS format) will
        get his way to Work:crypt.s in Amiga format.

     "crlf -D data.c1.print ms0:DATA.TXT"

        (Amiga ?) File data.c1.print will go to ms0:DATA.TXT in MS-DOS
        format.

     "crlf -pram: -s.mac MACFILES:#?"

        All files in the MACFILES: volume will go to ram: in Amiga format,
        with an extension of ".mac".
        Note: MACFILES:xxx -> ram:xxx.mac

     "crlf -v -pram: -s.mac MACFILES:#?"

        As above, but file names will be printed during the conversion.

     "crlf -! -A #?.c"

        Each and every C source in the current directory (collected from
        MS-DOS, Macintosh, Unix etc...) will be translated to Amiga
        format. Files will be overwritten.

     "crlf -lf -cr -cr -lf -s.odd #?"

        Each file in the current directory will be translated to the (odd)
        format
                xx xx xx xx xx lf cr cr lf
                yy yy yy yy yy lf cf cf lf
                      . . . . . .

        The resulting files will have an extension of ".odd"

     "crlf -sqq -! #?"

        This is illegal. Only one of -s or -! may be given. In this
        example, -! will be ignored and each file will go (in Amiga format)
        to <file>qq

     "crlf -v -M -pWork:mac/ Work:msdos/#?"

        Each file in the Work:msdos directory will be duplicated, in Mac
        format, in the Work:mac directory. File names will be printed at
        the terminal during the process.

     "crlf -D >ram:log -v -! #?.c #?.pas #?.s"

        Every file in the current directory ending in .c, .pas or .s get
        translated to MS-DOS format. A list of the conversions is leaved
        in ram:log.
        Note:   Using "#?.c|#?.pas" instead of "#?.c #?.pas" is more
                efficient and time-saving...



11.     Final note

     I hope CRLF will be of some use to you. If you have any bug report,
     suggestion or other, I can be reached at the following e-mail
     addresses:

        UUCP:           {rutgers|pyramid}!cbmvax!cbmehq!cbmita!icarus!vigi
        Internet:       [e-mail]
        FidoNet:        Vincenzo Gervasi  2:332/602

     This program is public domain.
     Only restriction is that the executable code and this document must
     go together in their original, unmodified state.

     Enjoy !




     Amiga and AmigaDOS are trademark of Commodore-Amiga, Inc.
     MS-DOS is a trademark of Microsoft Corp.
     Macintosh is a trademark of Apple Computer, Inc.
     UNIX is a trademark of Bell Laboratories.
     CRLF is not a trademark.






     V. Gervasi                                         Oct 15, 1991